home *** CD-ROM | disk | FTP | other *** search
/ BBS Toolkit / BBS Toolkit.iso / remote / rastat10.zip / RASTAT.DOC < prev    next >
Text File  |  1992-05-25  |  36KB  |  815 lines
  1.  
  2.     RAStat Documentation                                       Page 01 of 14
  3.     ════════════════════════════════════════════════════════════════════════
  4.     
  5.  
  6.       
  7.              RAStat v1.00  ──  RemoteAccess Statistical Generator
  8.       
  9.             Program and documentation copyright (c) 1992 Gary Ryno.
  10.  
  11.                             All rights reserved.
  12.                                      
  13.  
  14.  
  15.  
  16.  
  17.     Program Description:
  18.     ────────────────────
  19.     
  20.     RAStat is a full-featured statistical tool and display generator for
  21.     RemoteAccess Bulletin Board Systems.
  22.  
  23.     The program generates general information, system statistics, top user
  24.     and recent caller information in a RemoteAccess environment.  In
  25.     addition to its RA-specific features, RAStat has optional, enhanced
  26.     capabilities for systems that also operate FrontDoor.  RAStat produces
  27.     crisp ASCII and ANSI output files, which are properly formatted for
  28.     display from RA, using the type-5 menu option.
  29.  
  30.     Some of RAStat's principle features include:
  31.  
  32.       ■ Generation of overall system statistics: total upload/download/
  33.         message activity by current users, message base info, system calls,
  34.         etc.
  35.  
  36.       ■ Generation of "top ten" user statistics: top callers, message
  37.         writers, uploaders and downloaders (both number of files and
  38.         kbytes).
  39.  
  40.       ■ Generation of "today's calls" information: user calls, and
  41.         (optionally in a FrontDoor environment) inbound/outbound mailer
  42.         calls.
  43.  
  44.       ■ A high degree of flexibility and SysOp control: configuration,
  45.         operating modes, feature toggles, colors for ANSI output files, etc.
  46.  
  47.       ■ Rapid execution speed.
  48.  
  49.  
  50.     Warranty and Disclaimer:
  51.     ────────────────────────
  52.     
  53.     In three words, none and everything.
  54.  
  55.     RAStat is provided as-is, without warranty of any kind.  The program's
  56.     user assumes full responsibility for the use of this program, its
  57.     output, and its accompanying documentation, and for any harm or
  58.     consequences arising from such use.
  59.     
  60.  
  61.  
  62.  
  63.    
  64.     RAStat Documentation                                       Page 02 of 14
  65.     ════════════════════════════════════════════════════════════════════════
  66.     
  67.  
  68.     The program's author makes no warranty of any kind, either express or
  69.     implied, including, but not limited to, implied warranties of
  70.     merchantability or fitness for a particular purpose, with respect to
  71.     this software and accompanying documentation.
  72.  
  73.     In no event will the program's author be liable for damages of any kind
  74.     arising from the use of this program, its output, or its accompanying
  75.     documentation.  Use of this program constitutes acceptance of the above
  76.     provisions.
  77.  
  78.  
  79.     License:
  80.     ────────
  81.     
  82.     RAStat and its accompanying documentation are copyright (c) 1992 by
  83.     Gary Ryno.  All rights are reserved.  
  84.  
  85.     License is granted to use RAStat for any non-commercial application,
  86.     without compensation to the program's author.  RAStat is neither public
  87.     domain software or shareware; it is simply provided free of charge for
  88.     non-commercial uses.  You may not use RAStat for any commercial
  89.     application, ie: any purpose that earns or is intended to earn a profit,
  90.     or to further for-profit business activities.
  91.  
  92.     RAStat may be freely copied and distributed on magnetic or optical
  93.     media, or transmitted via modem, so long as no charge is levied for such
  94.     distribution.  Any copies so distributed shall include the executables,
  95.     support file(s) and accompanying documentation in their complete,
  96.     original, unmodified form.
  97.  
  98.     Neither the program or the accompanying documentation may be modified in
  99.     any way without the express written permission of the program's author. 
  100.     The RAStat files may, of course, be compressed or archived using any
  101.     compression format.
  102.  
  103.     Any use or distribution of this program beyond the scope of the license
  104.     described above, without the express written permission of the program's
  105.     author, constitutes a violation of copyright.
  106.  
  107.  
  108.     Why RAStat?  Wither the hobbyist?  (a brief, blunt editorial):
  109.     ──────────────────────────────────────────────────────────────
  110.     
  111.     I'm a veteran SysOp.  Why did I write RAStat?
  112.  
  113.     There are many other stat/info/call utilities available for
  114.     RemoteAccess.  Frankly, few are very impressive.
  115.  
  116.     Worse than the programs are the attitudes of some programmers.  Almost
  117.     every one of these gadgets was written by some poor, misguided fool who
  118.     expected to be sent money, mailed postcards, or otherwise paid homage
  119.     for having bestowed this junk on an innocent, unsuspecting world. 
  120.     Toward that end, almost every one of their programs was crippled,
  121.     keycoded or deliberately annoying.
  122.     
  123.  
  124.  
  125.  
  126.  
  127.     RAStat Documentation                                       Page 03 of 14
  128.     ════════════════════════════════════════════════════════════════════════
  129.     
  130.  
  131.     I get very perturbed whenever I encounter a minor BBS utility that's
  132.     littered with annoying "register me" garbage, has a drop-dead date, or
  133.     requires a keycode to run.  I imagine most other SysOps feel the same
  134.     way.  In BBS circles, this trend has reached the ludicrous stage.
  135.  
  136.     Running a BBS ── and programming BBS utilities ── is a hobby for most of
  137.     us, a way we've deliberately chosen to spend our leisure time.  It's
  138.     supposed to be fun.  Somewhere along the line, quite a few people seem
  139.     have forgotten that simple premise.  The best and the brightest started
  140.     coding BBS software a good number of years ago, observing such credos as
  141.     "absolutely free" and "militantly public domain".  Matter of fact, they
  142.     still do.  It's time everyone else got back to such a mindset.
  143.  
  144.     End of sermon.
  145.  
  146.     Use RAStat as you see fit.  It's free.  I hope you find it handy.
  147.  
  148.  
  149.     Hardware and Software Requirements:
  150.     ───────────────────────────────────
  151.     
  152.     RAStat requires RemoteAccess, unconditionally.  If you're not running a
  153.     RemoteAccess BBS, then RAStat is useless to you.
  154.  
  155.     RAStat will run on any IBM PC/XT/AT or compatible, under DOS v3.00 or
  156.     later.  The program executables require about 85 kb of diskspace. 
  157.     Modest additional diskspace will also be needed for its control and
  158.     output files.
  159.  
  160.     The program's memory needs vary somewhat, depending on the operating
  161.     mode and the size of your USERS.BBS and other system files.  Unless your
  162.     system files are unusually large, 220kb of RAM will typically be
  163.     sufficient.  In any event, RAStat should run in any memory window that
  164.     is satisfactory for either RA or FD.
  165.  
  166.     RAStat has been tested successfully under DESQview, however has no
  167.     specific DV-aware features.  It has not been tested in any other
  168.     multitasking environment.
  169.  
  170.     The RAStat executables have been successfully tested after being
  171.     compressed with both PKLite and LZExe.  RAStat has not been tested under
  172.     Stacker, or using any other method of runtime compression/decompression.
  173.     
  174.     RAStat is hardcoded for the file structures used by RemoteAccess v1.11
  175.     and (optionally) FrontDoor v2.02/nc.  It has not been tested with
  176.     earlier, obsolete versions of either program.  It will continue to work
  177.     with later versions of both programs, so long as the structures of the
  178.     USERS.BBS, LASTCALL.BBS, INBOUND.HIS and OUTBOUND.HIS files remain
  179.     substantially unchanged.
  180.     
  181.  
  182.  
  183.  
  184.  
  185.     RAStat Documentation                                       Page 04 of 14
  186.     ════════════════════════════════════════════════════════════════════════
  187.     
  188.  
  189.     Program Installation:
  190.     ─────────────────────
  191.     
  192.     As distributed, the complete RAStat package consists of seven files:
  193.  
  194.       ■ RASTAT.EXE   [program executables]
  195.       ■ RASTAT.CTL   [sample control file]
  196.       ■ RASTAT.DOC   [documentation]
  197.       ■ STATS.A??    [two sample stats mode output files, ASCII and ANSI]
  198.       ■ CALLS.A??    [two sample calls mode output files, ASCII and ANSI]
  199.  
  200.     Only RASTAT.EXE and RASTAT.CTL are necessary for the program's
  201.     operation.  RAStat may be installed and run from anywhere on the system;
  202.     simply copy RASTAT.EXE and RASTAT.CTL to the desired directory.
  203.  
  204.     There is one important factor to consider during installation: the
  205.     RASTAT.CTL file will need to be in the current directory when the
  206.     program is run.  Having this in mind, the flow of your system's batch
  207.     file(s) will best dictate where RAStat should be installed.  On the
  208.     typical BBS, the RA system directory is the most convenient place.
  209.  
  210.  
  211.     Program Configuration:
  212.     ──────────────────────
  213.     
  214.     RAStat requires its own control file, RASTAT.CTL.  Everything the
  215.     program needs to know is contained in this single file; it doesn't need
  216.     to have the RA or FD environment variables set, nor does it care about
  217.     the *.RA or *.FD files.  This approach was selected to make RAStat
  218.     adaptable to virtually any system.
  219.  
  220.     The control file is flat ASCII text.  It may be edited with DOS EDLIN, a
  221.     text editor, or a word processor (in the latter case, be certain to save
  222.     the file in non-document mode, ie: as raw ASCII text).
  223.  
  224.     The control file MUST be named RASTAT.CTL, and again, it MUST be in the
  225.     current directory when RAStat is executed.  If RAStat is unable to find
  226.     and/or read the control file, the program will abort.  
  227.  
  228.     The fastest way to get RAStat up and running is to edit the sample
  229.     RASTAT.CTL file to fit your system and needs.  The sample file is
  230.     heavily commented, and should be largely self-explanatory.  It is
  231.     explained in greater detail below.
  232.  
  233.     RASTAT.CTL may contain as many comment lines as you wish.  Comment lines
  234.     begin with a semicolon (;) as the first character, and are ignored by
  235.     the program.  No comment lines are required; without them, a small
  236.     amount of diskspace will be saved, and the program will initialize
  237.     slightly faster. 
  238.  
  239.     Non-comment lines in RASTAT.CTL begin with a keyword.  All valid
  240.     keywords and their correct usage are detailed below.  Keywords are case
  241.     insensitive, and may appear in RASTAT.CTL in any order.  Keywords must
  242.     be spelled exactly as shown below, and they may not be proceeded by
  243.     spaces.
  244.     
  245.  
  246.  
  247.  
  248.  
  249.     RAStat Documentation                                       Page 05 of 14
  250.     ════════════════════════════════════════════════════════════════════════
  251.     
  252.  
  253.     Several keywords require a parameter.  There must be EXACTLY one blank
  254.     space (not three spaces, or two, or a tab, but ONE space) between the
  255.     keyword and the parameter.
  256.  
  257.     Several keywords require a DOS path as a parameter.  The paths specified
  258.     in the control file MUST exist; RAStat will not create them, and the
  259.     program will abort if they don't exist.  A trailing backslash (\) is
  260.     optional on all path parameters.
  261.  
  262.     Several keywords toggle features on/off.  In the sample control file,
  263.     all are enabled by default.  To disable these features, comment-out the
  264.     keyword with a semicolon.
  265.  
  266.     All keyword lines in the control file MUST be terminated by a CRLF
  267.     immediately after the last significant text character; trailing spaces
  268.     or trailing comments are NOT permitted (for the non-technical reader:
  269.     press [Enter] after the last character on the line).
  270.  
  271.     Invalid lines and invalid keywords will either cause RAStat to abort, or
  272.     will be ignored by the program, depending on the circumstances.
  273.  
  274.     A detailed description of each keyword and its correct usage follows
  275.     (stats mode and calls mode are explained under "Program Operation").
  276.  
  277.       ■ BBSName          [usage: BBSName Name]
  278.  
  279.         The name of your BBS.  The name is used by RAStat to personalize its
  280.         output files to your system.  The BBSName parameter may be up to 30
  281.         characters long, and may include any printable character, including
  282.         spaces.  Excess characters are truncated.  BBSName is mandatory for
  283.         all modes.
  284.  
  285.       ■ RAPath           [usage: RAPath c:\ra\]
  286.  
  287.         The complete path to your RemoteAccess USERS.BBS and LASTCALL.BBS
  288.         files, as defined in CONFIG.RA.  RAPath is mandatory for all modes.
  289.  
  290.       ■ TextPath          [usage: TextPath c:\ra\text\]
  291.  
  292.         The complete path to the directory where RAStat is to write its
  293.         output files.  Normally, this should be the RA textfiles directory,
  294.         as defined in CONFIG.RA.  However, if you have special needs, you
  295.         can specify any directory on the system.  TextPath is mandatory for
  296.         all modes.
  297.  
  298.       ■ FDPath           [usage: FDPath c:\fd\]
  299.  
  300.          The complete path to your FrontDoor INBOUND.HIS and OUTBOUND.HIS
  301.          files, as defined in SETUP.FD.  FDPath is mandatory for calls
  302.          mode if FDCalls is enabled, and is ignored otherwise.
  303.          
  304.  
  305.  
  306.  
  307.  
  308.     RAStat Documentation                                       Page 06 of 14
  309.     ════════════════════════════════════════════════════════════════════════
  310.     
  311.  
  312.       ■ StatsFile        [usage: StatsFile filename]
  313.  
  314.         The base filename for the stats mode output files.  These files will
  315.         be written to the TextPath directory, using the name specified, in
  316.         both ASCII and ANSI format.  Do NOT include a path or extension with
  317.         the filename; RAStat will insert them.  StatsFile is mandatory for
  318.         stats mode, and is ignored otherwise.
  319.  
  320.       ■ CallsFile        [usage: CallsFile filename]
  321.  
  322.         The base filename for the calls mode output files.  These files will
  323.         be written to the TextPath directory, using the name specified, in
  324.         both ASCII and ANSI formats.  Do NOT include a path or extension
  325.         with the filename; RAStat will insert them.  StatsFile is mandatory
  326.         for stats mode, and is ignored otherwise.
  327.  
  328.         Note:  StatsFile and CallsFile MUST each specify a unique filename.
  329.                DON'T try using the same filename for both, it will NOT work!
  330.  
  331.       ■ FDCalls          [usage: FDCalls]
  332.  
  333.         This parameter tells RAStat whether or not to generate FD mailer
  334.         call information when running in calls mode.  If FDCalls is enabled,
  335.         the day's mailer calls will be detailed in the calls mode output
  336.         files, in addition to the day's user calls.  Comment-out to disable.
  337.         FDCalls is optional for calls mode, and is ignored otherwise.
  338.  
  339.       ■ SysopExclude     [usage: SysopExclude]
  340.  
  341.         This parameter tells RAStat whether or not to exclude the SysOp
  342.         (defined as the first record in USERS.BBS) from its output files. 
  343.         If SysopExclude is enabled, then the first user in USERS.BBS will
  344.         NEVER appear in any of RAStat's output files.  Comment-out to
  345.         disable.  SysopExclude is optional, and affects all modes.
  346.  
  347.       ■ HiddenExclude    [usage: HiddenExclude]
  348.  
  349.         This parameter tells RAStat whether or not to exclude users who have
  350.         the hidden attribute set in USERS.BBS from its output files.  If
  351.         HiddenExclude is enabled, then users with the hidden attribute set
  352.         will NEVER appear in RAStat's output files.  Comment-out to disable.
  353.         HiddenExclude is optional, and affects all modes.
  354.  
  355.       ■ Quiet            [usage: Quiet]
  356.  
  357.         RAStat only beeps the speaker (once) if an error occurs.  If the
  358.         Quiet parameter is enabled, ALL speaker sounds are silenced while
  359.         the program is running.  Comment-out to disable.  Quiet is optional,
  360.         anf affects all modes.
  361.  
  362.         Note: There is one exception to Quiet mode.  If RAStat aborts
  363.               because it cannot find and/or read the RASTAT.CTL file, it
  364.               WILL beep the speaker once, unconditionally.
  365.               
  366.  
  367.  
  368.  
  369.  
  370.     RAStat Documentation                                       Page 07 of 14
  371.     ════════════════════════════════════════════════════════════════════════
  372.     
  373.  
  374.       ■ Title            [usage:  Title ##]
  375.       ■ Header           [usage:  Header ##]
  376.       ■ Data             [usage:  Data ##]
  377.       ■ Prompt           [usage:  Prompt ##]
  378.       ■ Background       [usage:  Background ##]
  379.  
  380.         These parameters specify the colors to be used in each field in the
  381.         ANSI output files.  Only one background color is permitted; the
  382.         other keywords all specify foreground colors for each of the various
  383.         fields.  A list of the available colors and their corresponding
  384.         numbers follows below.  The color parameters are mandatory for all
  385.         modes.
  386.       
  387.         To start, it is recommended that you view the sample ANSI files
  388.         included with RAStat.  They were generated using the default colors
  389.         specified in the sample control file.  Once you have a feel for the
  390.         various fields, adjust the colors to suit your preferences.
  391.  
  392.         Note: RAStat only checks the color parameters for numeric validity
  393.               (ie: if you specify a number outside of the valid ranges, such
  394.               as a foreground-only color for the background, the program
  395.               will abort).
  396.  
  397.               RAStat does NOT check the colors for visual/aesthetic
  398.               characteristics.  If you specify hideous color combinations,
  399.               RAStat will merrily generate them for you.  Ditto, if you
  400.               specify black on black, that's exactly what you'll get: an
  401.               all-black, apparently blank field.
  402.  
  403.         Valid color parameters:
  404.  
  405.         Background        Foreground
  406.         ────────────      ─────────────────────────────────
  407.         00 = Black        00 = Black     08 = Dark grey
  408.         01 = Blue         01 = Blue      09 = Bright blue
  409.         02 = Green        02 = Green     10 = Bright green
  410.         03 = Cyan         03 = Cyan      11 = Bright cyan
  411.         04 = Red          04 = Red       12 = Bright red
  412.         05 = Magenta      05 = Magenta   13 = Bright magenta
  413.         06 = Brown        06 = Brown     14 = Bright yellow
  414.         07 = Gray         07 = Gray      15 = Bright white
  415.  
  416.  
  417.     Program Operation:
  418.     ──────────────────
  419.     
  420.     RAStat has two different operating modes: stats and calls.  They are
  421.     totally independent from each other.  At your option, you may use either
  422.     or both.
  423.  
  424.     The operating mode(s) are specified by DOS command line parameter:
  425.  
  426.       ■ rastat -stats         [generate statistical and top user files only]
  427.       ■ rastat -calls         [generate today's calls files only]
  428.       ■ rastat -stats -calls  [generate both]
  429.         
  430.  
  431.  
  432.  
  433.  
  434.     RAStat Documentation                                       Page 08 of 14
  435.     ════════════════════════════════════════════════════════════════════════
  436.     
  437.  
  438.     RAStat has no other command line parameters.  The parameters are case
  439.     insensitive, and may appear in any order.  They may be prefaced by a
  440.     dash (-), a forward slash (/), or a blank space; the program can handle
  441.     all three forms.  RAStat will abort to a help screen if at least one
  442.     valid parameter isn't specified on the command line.  Invalid parameters
  443.     are otherwise ignored.
  444.  
  445.     In stats mode, RAStat generates ASCII and ANSI files depicting general
  446.     system information, an overall statistical summary of user activity, and
  447.     the system's top ten users in each of six different categories (logons,
  448.     messages posted, files uploaded, kbytes uploaded, files downloaded, and
  449.     kbytes downloaded).
  450.  
  451.     The "general info" portion of the stats output files utilize several
  452.     imbedded RA control codes, to display real-time information when the
  453.     file is viewed from RA.  These include the current date and time, time
  454.     to the next event, total number of logons, total number of users, and a
  455.     message base summary.
  456.  
  457.     In calls mode, RAStat generates ASCII and ANSI files depicting the day's
  458.     BBS calls, including each caller's name, location, number of calls, BPS
  459.     rate and on/off time, and a running total of the day's total logons.
  460.  
  461.     In a FrontDoor environment, the calls output files will also include the
  462.     day's inbound/outbound mailer calls, if FDCalls is enabled.  The FDCalls
  463.     output includes the remote link's node number and system name, bytes
  464.     received and sent, cost, session time, and a summary of the day's total
  465.     mail activity.
  466.  
  467.     To get a better feel for the exact information that RAStat generates,
  468.     and to see how the data is formatted, please refer to the sample output
  469.     files.  They illustrate the program's capabilities far more clearly than
  470.     would any long-winded description here.
  471.  
  472.     RAStat is quite fast.  No matter how often you choose to run the
  473.     program, it won't bog-down your system, or significantly increase its
  474.     recycle time.  For example, it typically takes RAStat less than 10
  475.     seconds to do a full stats run on a 350-record USERS.BBS, using a modest
  476.     10 mhz AT-class machine.  Calls mode is even faster; typically less than
  477.     5 seconds, even with FDCalls enabled and 500-record *.HIS files. 
  478.     Obviously, actual execution time will depend on the speed of your
  479.     computer, and the size of your system files.
  480.  
  481.     You can run stats mode as often or as seldom as you wish.  Once per day
  482.     during your maintenance event is quite sufficient.  Alternatively, if
  483.     you prefer the most up-to-the-minute data online at all times, stats
  484.     mode can be run periodically throughout the day, or after every user
  485.     logoff.
  486.  
  487.     Calls mode has somewhat stricter requirements: in order to maintain
  488.     reasonably current files of the day's calls, calls mode needs to be run
  489.     at the proper times.  At minimum, calls mode should be run after every
  490.     user logoff.  If you have FDCalls enabled, you may prefer to do a calls
  491.     run just before loading FrontDoor each cycle, for the most
  492.     up-to-the-minute data.
  493.     
  494.  
  495.  
  496.  
  497.    
  498.     RAStat Documentation                                       Page 09 of 14
  499.     ════════════════════════════════════════════════════════════════════════
  500.     
  501.  
  502.     As a starting point, you might try the setup I use on my own BBS:
  503.     RAStat -stats once per day during maintenance, and RAStat -calls before
  504.     each FrontDoor cycle.  All output files can also be generated at once
  505.     during the same run: simply specify both -stats and -calls on the
  506.     command line.
  507.  
  508.     Again, it must be stressed that stats mode and calls mode are completely
  509.     autonomous.  Each mode performs a different function, and is totally
  510.     independent of the other.  If you wish, you may use only stats mode.
  511.     Or only calls.  Or both.  However you choose to configure and operate
  512.     RAStat, the program will do precisely what you want it to.
  513.     
  514.     Obviously, RAStat was designed for unattended operation, under batch
  515.     file control.  It's entirely up to you to add the necessary lines to
  516.     your system's batch file(s) to invoke RAStat at the appropriate times.
  517.     
  518.     Running RAStat manually when shelled from RA [Alt-J] is NOT recommended.
  519.  
  520.     When running in either mode, RAStat needs access to your RemoteAccess
  521.     USERS.BBS and LASTCALL.BBS files.  In calls mode with FDCalls enabled,
  522.     it also needs access to the FrontDoor INBOUND.HIS and OUTBOUND.HIS
  523.     files.  If RAStat is unable to locate and/or read any of the files it
  524.     needs to operate in the current mode(s), it will abort.  In these cases,
  525.     any pre-existing output files will remain unchanged.
  526.  
  527.     When RAStat writes its output files to disk, the new files overwrite any
  528.     old files of the same name.  Calls mode output files are automatically
  529.     reset each day, the first run after midnight.
  530.  
  531.     If FDCalls is enabled, it makes no difference how long you retain
  532.     FrontDoor's *.HIS files.  RAStat searches the *.HIS files for the first
  533.     record matching the current date, and then reads from that point to the
  534.     end of the file; even if your *.HIS files overlap multiple months, they
  535.     won't break RAStat.
  536.  
  537.  
  538.     Multiline Considerations:
  539.     ─────────────────────────
  540.     
  541.     When RAStat accesses the USERS.BBS, LASTCALL.BBS, INBOUND.HIS and
  542.     OUTBOUND.HIS files, it opens them as read-only, write-locked.  They are
  543.     opened in this manner to absolutely protect them from any possible
  544.     corruption.  If you run a multiline BBS, this may cause potential
  545.     sharing problems, should RA or FD try to open one of those files for
  546.     read/write access while RAStat has it open.
  547.  
  548.     If the nature of your system is such that you need to prevent RAStat
  549.     from accessing the above files at certain times, it is ENTIRELY your
  550.     responsibility to prevent it from doing so by semaphoring as necessary
  551.     from your batch file(s).  RAStat does NOT write semaphore files of its
  552.     own, and it does NOT look for semaphore files written by other programs. 
  553.     In simplest terms, when you run RAStat, it runs.  Unconditionally,
  554.     period.
  555.     
  556.  
  557.  
  558.  
  559.  
  560.     RAStat Documentation                                       Page 10 of 14
  561.     ════════════════════════════════════════════════════════════════════════
  562.     
  563.  
  564.     Displaying RAStat's Output Files:
  565.     ─────────────────────────────────
  566.     
  567.     RAStat's ASCII and ANSI output files are always written to the TextFile
  568.     directory, named according to the specifications in RASTAT.CTL.
  569.  
  570.     The output files are formatted for display from RemoteAccess, using RA
  571.     control codes.  Each file is broken-down into multiple screens, each
  572.     separated by the usual "Press [Enter] to continue: ^A^L".
  573.  
  574.     It's entirely up to you to setup the necessary RA menu commands to
  575.     display RAStat's output files on your BBS.  You can display them however
  576.     you wish.  They are best suited for online display using RA's type-5
  577.     textfile option.  Alternatively, they may also be displayed from a
  578.     type-6 selection menu, as logon bulletins, or in any of several other
  579.     ways, limited only by RA's internal capabilities and your own
  580.     imagination.
  581.  
  582.     It is suggested that you avoid using the RA display options that append
  583.     the "Press [Enter] to continue: ^A" sequence at the end of file. 
  584.     RAStat's files already have them, and if you have RA append another,
  585.     your users will end-up needing to press [Enter] twice to return to the
  586.     menu.
  587.  
  588.     As a starting point, you might try the setup I use on my own BBS: I keep
  589.     the RAStat output files in the RA textfiles directory, named STATS.A??
  590.     and CALLS.A??, and use a pair of type-5 options to display them.
  591.  
  592.     Sample output files are included for your review.  All of the RA control
  593.     codes have been removed from the samples.  View the sample files using
  594.     the DOS TYPE [FILE.EXT] | MORE command... they are formatted to appear
  595.     roughly the same as the real files will appear when displayed from RA.
  596.         
  597.     Although RemoteAccess supports AVATAR, RAStat does not have the
  598.     capability to generate files in the AVT/0+ format.  This was a
  599.     deliberate programming decision.  Rapid operation and reasonable
  600.     executable size were two key goals for RAStat.  AVATAR hasn't yet
  601.     attained widespread use, and adding AVATAR support would have increased
  602.     RAStat's size and reduced its speed, for very little gain.
  603.  
  604.     If AVATAR format files are critical to your system, you can easily
  605.     create them from RAStat's ANSI output files, using the AVTCONV
  606.     conversion utility; call AVTCONV from your batch file immediately after
  607.     RAStat is run.  AVTCONV is currently being included in the RemoteAccess
  608.     distribution archives, and should also be available on any RA Support
  609.     System.
  610.  
  611.  
  612.     Program Limitations:
  613.     ────────────────────
  614.     
  615.     In general, RAStat's limitations parallel those imposed by the RA and FD
  616.     file structures.  For example, most numeric data in USERS.BBS is stored
  617.     as 2-byte (16-bit) signed integers, which have a maximum positive value
  618.     of 32,767.  If you have a user who's managed to logon 32,768 times or
  619.     post 32,768 messages, he'll overflow RAStat's capabilities (and RA's).
  620.     
  621.  
  622.  
  623.  
  624.  
  625.     RAStat Documentation                                       Page 11 of 14
  626.     ════════════════════════════════════════════════════════════════════════
  627.     
  628.  
  629.     Nonetheless, RAStat does have a few limitations of its own.  Most are
  630.     cosmetic, to insure that the program's output files don't exceed 80
  631.     characters in width.  String fields, such as user names, are truncated
  632.     to fit if necessary.  It's rather doubtful that you'll ever exceed
  633.     RAStat's numeric capabilities, but if you do, no real harm will be
  634.     done: the resulting output files just won't be very pretty.
  635.  
  636.     For the record, here's the full rundown:
  637.  
  638.       ■ String fields
  639.       
  640.         User names:       25 characters
  641.         User locations:   24 characters
  642.         User BPS rates:   5 characters (fixed: 300, 1200, 2400, 4800, 7200,
  643.                           9600, 12000, 14400, 19200, 38400 or Local)
  644.         System names:     30 characters
  645.         Node number:      13 characters (sufficient for xxx:yyyy/zzzz, point
  646.                           numbers are never displayed)
  647.         Dates:            8 characters (fixed: mm/dd/yy)
  648.         Times:            5 characters (fixed: hh:mm)
  649.  
  650.  
  651.       ■ Numeric fields:
  652.  
  653.         Total ul/dl:      modified floating point, 6 digits (0 to 999,999)
  654.         Total upmb/dnmb:  modified floating point, 6 digits (0 to 9999.99)
  655.         Total msgs:       modified floating point, 6 digits (0 to 999,999)
  656.         Avg ul/dl:        modified floating point, 6 digits (0 to 9999.99)
  657.         Avg upkb/dnkb:    modified floating point, 6 digits (0 to 9999.99)
  658.         Avg msgs:         modified floating point, 6 digits (0 to 9999.99)
  659.         Cost:             modified integer, 4 digits (0 to 9999, with the
  660.                           string character "¢" appended)
  661.         Bytes rx/tx:      modified long integer, 8 digits (0 to 99,999,999)
  662.         Total rx/tx:      long integer, 10 digits (0 to 2,147,483,648)
  663.         All other:        integer, 5 digits (0 to 32,767)
  664.  
  665.  
  666.       ■ Miscellaneous:
  667.  
  668.         Max calls/day:    255 (ie: 255 entries each, user/inbound/outbound)
  669.         Max *.BBS files:  limited only by available RAM
  670.         Max *.HIS files:  limited only by available RAM
  671.         Min USERS.BBS:    11 records, not including excluded users
  672.         
  673.  
  674.  
  675.  
  676.  
  677.     RAStat Documentation                                       Page 12 of 14
  678.     ════════════════════════════════════════════════════════════════════════
  679.     
  680.  
  681.     Program Errors:
  682.     ───────────────
  683.     
  684.     All "expected" external errors are trapped by the program.  "Expected
  685.     errors" include just about every mistake you can make in configuring or
  686.     running RAStat (bad file names, invalid control file options, etc.), and
  687.     all of the routine external problems you might encounter (missing paths,
  688.     insufficient diskspace, etc).  If RAStat aborts due to any of these
  689.     external errors, the program will display an error-specific help screen
  690.     that explains exactly what's wrong and how to fix it.
  691.  
  692.     RAStat does not set DOS errorlevels on exit, and it has no logging
  693.     capabilities.
  694.  
  695.  
  696.     Revision History:
  697.     ─────────────────
  698.     
  699.       ■ v0.1α   Initial structures defined.  Stats mode and ASCII write
  700.                 routines implemented.  Developmental testing.
  701.  
  702.       ■ v0.2α   Existing code refined.  Calls mode (user) routines
  703.                 implemented.  Developmental testing.
  704.  
  705.       ■ v0.3α   Existing code refined.  FDCalls, control file and error-
  706.                 handling routines implemented.  Developmental testing.
  707.  
  708.       ■ v0.4α   Existing code refined.  ANSI write routines implemented.
  709.                 Alpha testing on 1:202/302.
  710.  
  711.       ■ v0.5ß   Existing code optimized for improved speed and memory
  712.                 management.  Beta testing on 1:202/302 and 1:202/501.
  713.                 
  714.       ■ v0.6ß   Final beta version.  Minor bugfixes and cosmetic changes.
  715.                 Beta testing on 1:202/302 and 1:202/501.
  716.                 
  717.       ■ v1.00   First public release.  Distributed via SDS.
  718.  
  719.     Planned future enhancements for RAStat include a small database function
  720.     that will allow generation of perpetual system statistics and other
  721.     long-term, historical information that the existing RA structures don't
  722.     provide for.
  723.  
  724.     A companion program, FDStat, is also in the design stages.  It will
  725.     include the capabilities of RAStat's FDCalls feature, together with
  726.     other FD-specific functions.
  727.     
  728.  
  729.  
  730.  
  731.  
  732.     RAStat Documentation                                       Page 13 of 14
  733.     ════════════════════════════════════════════════════════════════════════
  734.     
  735.  
  736.     Contacting the Author:
  737.     ──────────────────────
  738.     
  739.     I welcome any comments regarding RAStat, and suggestions for future
  740.     versions.  The program has been thoroughly tested and is believed to be
  741.     error-free, but if you discover an error, bug reports will certainly be
  742.     appreciated.  Flames are never dignified with a response.
  743.  
  744.     I prefer to communicate via electronic mail, and can be reached as
  745.     follows:
  746.  
  747.       ■ BBS:         Gandalf's, 619-466-9505, 300-14400 bps HST, 8N1, 24 hrs
  748.  
  749.       ■ FidoNet:     1:202/302.0
  750.  
  751.       ■ Usenet:      gryno@gandalfs.UUCP  (ucsd!serene!jbbs!gandalfs!gryno)
  752.  
  753.                      or:  gryno@f302.n202.z1.fidonet.org
  754.  
  755.       ■ CompuServe:  70671/1660
  756.  
  757.       ■ Bix:         gryno
  758.  
  759.  
  760.     The latest version of RAStat is always available for download (first
  761.     call) on my BBS, at the above number.  Nodelisted FidoNet SysOps (2400 bps
  762.     or faster) may also FReq the latest version from me using magic name
  763.     RASTAT, anytime except ZMH.  Major revisions will be distributed via SDS.
  764.     
  765.  
  766.     Acknowledgements:
  767.     ─────────────────
  768.     
  769.     Special thanks to Frank Hicinbothem, 1:202/501... beta tester, friend,
  770.     trusted adviser, and general guru.
  771.     
  772.     Thanks to the Software Distribution System (SDS) nodes for distributing
  773.     RAStat and countless other fine programs at their own expense.
  774.  
  775.     RemoteAccess is a trademark of Andrew Milner and Continental Software.
  776.         
  777.     The RemoteAccess Avatar Conversion Utility (AVTCONV) is a copyright-
  778.     protected program written by S/e/m/a/j Communications.
  779.  
  780.     FrontDoor is a trademark of Joaquim Homrighausen and Advanced
  781.     Engineering sarl.
  782.  
  783.     DESQview is a trademark of Quarterdeck Office Systems, Inc.
  784.  
  785.     PKLite is a trademark of Phil Katz and PKWare.
  786.  
  787.     LZExe is a freeware program written by Fabrice Bellard of Grabels, France.
  788.     
  789.     Stacker is a trademark of Stac Electronics.
  790.     
  791.     IBM PC, PC/XT and PC/AT are trademarks of IBM.
  792.  
  793.  
  794.     RAStat Documentation                                       Page 14 of 14
  795.     ════════════════════════════════════════════════════════════════════════
  796.     
  797.  
  798.     Dedication:
  799.     ───────────
  800.     
  801.       With great esteem and respect, RAStat is dedicated to the memory of:
  802.  
  803.              Robert Michael Ivins (August 3, 1947 - March 9, 1991)
  804.  
  805.                               Photojournalist,
  806.                      San Diego Union/Tribune Newspaper
  807.                          United Press International
  808.                               Associated Press
  809.  
  810.                            Winner, Pulitzer Prize
  811.  
  812.  
  813.  
  814.  
  815.